Writing Your Own Balloon Definition Function
your help balloons, and the standard balloon definition function
provides a consistent, attractive general shape to balloons across all
applications.
Though it takes extra work on your part and your balloons will not
share the consistent appearance of help balloons used by the Finder and
by other applications, you can create your own balloon definition
function. The balloon definition function defines the appearance of the
help balloon. A help balloon is a special type of window. You implement
a balloon definition function by writing a window definition function
that performs the tasks described in this section. The standard balloon
definition function is of type 'WDEF' with resource ID 126.
A balloon definition function is responsible for calculating the content
region and structure region of the help balloon window and drawing the
frame of the help balloon. The content region is the area inside the
balloon frame; it contains the user help information. The structure
region is the boundary region of the entire balloon, including the
content area and the pointer that extends from one of the help balloon's
corners. (The third Figure in
standard help balloons.)
enclose the help information and determines where to display the help
balloon. The
breaks in the help information. The Help Manager determines where to display the help balloon based on the tip location and alternate
rectangle.
the rectangle. This distance allows for the tip of the help balloon. Note
that the tip must always align with an edge of the boundary rectangle.
rectangle for the help balloon window.
balloon. TheHelp Manager specifies the calculated rectangle and the window definition ID as parameters to the NewWindow function. The NewWindow function calls the balloon definition function in the same manner as a window definition function.
window definition function.)
four parameters: the variation code that specifies the shape and
relative tip position of the help balloon, a pointer to the window, the
action to perform, and a parameter that has variable contents
depending on the action to perform.
Here's an example that shows the declaration for a balloon definition
function called MyBalloonDef.
long MyBalloonDef ( short variant, WindowPtr theBalloon, short message, long param);
The variant parameter is the variation code used to specify the shape
and position of the help balloon. You should use the same relative
position for the tip of the help balloon that the standard variation codes
0 through 7 specify (see the third Figure in
balloon points to the object that the help balloon describes.
The parameter theBalloon is a pointer to the window of the help
balloon.
The message parameter identifies the action your balloon definition
function should perform. Your balloon definition function can be sent
the same messages as a window definition function, but the only ones
your balloon definition function needs to process are the wDraw and
When your balloon definition function receives the wCalcRgns
message, your function should calculate the content region and
structure region of the help balloon.
When your balloon definition function receives the wDraw message,
your function should draw the frame of the help balloon.
If you want to process other messages in your balloon definition
function (for example, performing any additional initialization), you
can also process the other standard 'WDEF' messages.
The value of the param parameter depends on the value of the message
parameter. The wCalcRgns and wDraw messages do not use this
parameter.
function, you specify its resource ID and the desired variation code
either in the HMShowBalloon function or in the appropriate fields of the 'hmnu', 'hdlg', or 'hrct' resources. The Help Manager derives your balloon's window definition ID from its resource ID.